.\" Copyright (c) 2010\-2012 Plowshare Team
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 3 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" <http://www.gnu.org/licenses/>.

.TH "plowdown" "1" "July 1, 2012" "GPL" "Plowshare GIT-snapshot"

.SH NAME
plowdown \- Command-line downloader for file-sharing websites

.SH SYNOPSIS
.B plowdown
[\fIOPTIONS\fP]...
[\fIMODULE_OPTIONS\fP]...
\fIURL\fP|\fIFILE\fP
[\fIURL\fP|\fIFILE\fP]...

.SH DESCRIPTION
.B plowdown
is a set of bash scripts designed for automatic downloads on file-sharing website.
It acts like a web browser, retrieving pages and filling html forms (including captchas).

Currently supported hosting sites list is available in README file.

.\" ****************************************************************************
.\" * Options                                                                  *
.\" ****************************************************************************
.SH OPTIONS

.SS Common options
.TP
.B -c, --check-link
Check and write alive link(s) to standard output, files are not downloaded.
.TP
.B -m, --mark-downloaded
Mark downloaded links in (regular) file arguments.
.TP
.BI -o, " " --output-directory "=DIRECTORY"
Directory where files will be saved. Default is current directory.
.TP
.B -x, --no-overwrite
Do not overwrite existing files. Existing file will be preserved and filename will be
suffixed with .1, .2, and so on.
.SS Logging options
.TP
.BI -v, " " --verbose "=LEVEL"
Set output verbose level:
.RS 
\fB0\fR  none,
.RE
.RS 
\fB1\fR  errors,
.RE
.RS
\fB2\fR  notice (default behavior),
.RE
.RS
\fB3\fR  debug,
.RE
.RS
\fB4\fR  report (very noisy, log HTML pages).
.RE
.TP
.B -q, --quiet
Alias for \fB-v0\fR. Do not print any debug messages.
.SS Tuning settings
.TP
.BI -i, " " --interface "=IFACE"
If your machine has several network interfaces, force using \fIIFACE\fR interface.
.TP
.BI "   " " " --max-rate "=SPEED"
Limit download speed in bytes per seconds. Suffixes are:
.RS 
\fBk\fR  for kilobytes (kB),
.RE
.RS
\fBm\fR  for megabytes (MB),
.RE
.RS
\fBg\fR  for gigabytes (GB).
.RE
.TP
.BI -t, " " --timeout "=SECS"
Cancel download after \fISECS\fR seconds of waits. Apply on module exit value: \fB10\fR (temporary unavailable error).
This error can be returned in various cases: unallowed parallel download, daily downloads limit reached, remote hoster overloaded.
Default option value is disabled (no timeout, infinite) and applies for one single URL download.
.TP
.BI -r, " " --max-retries "=N"
Set maximum retries for download failures. Apply on module exit value: \fB3\fR (network error), \fB7\fR (captcha error).
Default option value is 2 (i.e. 3 tries) and applies for one single URL download.
.TP
.BI "   " " " --antigate "=KEY"
Use Antigate.com service to solve captcha.
.TP
.BI "   " " " --captchatrader "=USER:PASSWORD"
Use Captcha Trader service to solve captcha.
.TP
.BI "   " " " --deathbycaptcha "=USER:PASSWORD"
Use Death by Captcha service to solve captcha.
.TP
.BI "   " " " --captchamethod "=METHOD"
Force specific captcha solving method. Available values:
.RS
\fBimgur\fR : upload image to Imgur.com service, print image url in console. Useful for NAS and embedded devices.
.RE
.RS
\fBnone\fR : abort if captcha solving is requested (even if automatic solving service is available).
.RE
.RS
\fBonline\fR : use captcha solving website (Antigate, CaptchaTrader or DeathByCaptcha account required).
.RE
.RS
\fBnox\fR : display image in console (text) and prompt for manual entering. Looks for ascii viewers: img2txt, aview, tiv.
.RE
.RS
\fBprompt\fR : display image (X11 or text) and prompt for manual entering. Looks for viewers: display, sxiv, qiv, img2txt, aview, tiv.
.RE
.TP
.BI "   " " " --captchaprogram "=SCRIPT"
Call external program (or script) for solving captcha.

Three arguments are given:
.RS
\fB$1\fR
module name (lowercase). For example: \fImediafire\fR.
.RE
.RS
\fB$2\fR
image filename (with full path).
.RE
.RS
\fB$3\fR
hint or captcha type (string)

Return value and exit status:
.RE
.RS
\fB0\fR : solving success. Result must be printed on stdout.
.RE
.RS
\fB2\fR : external solver is not able to solve requested captcha. Let plowdown continue solving it normally (will consider \fI--captchamethod\fP if specified).
.RE
.RS
\fB7\fR : external solver failed.
Note: this exit code is eligible with retry policy (\fI-r/--max-retries\fP).

Note: plowdown legacy exit errors can also be returned, for example: \fB1\fR (fatal) or \fB3\fR (network).
.RE
.TP
.BI "   " " " --temp-directory "=DIRECTORY"
Directory where files are temporarily downloaded.
.TP
.B "   " --temp-rename
Append .part suffix to filename while file is being downloaded. Download resume will not work with this option.
.SS Miscellaneous options
.TP
.BI "   " " " --cookies "=FILE"
Use provided cookie file for HTTP requests. This can be used to bypass login process on registered (premium) accounts.
This is not implemented by all modules.
.TP
.B "   " --fallback
If no module is found for link, simply download it (HTTP GET).
.TP
.B "   " --no-curlrc
Do not use curl config file (~/.curlrc).
.TP
.B "   " --no-plowsharerc
Do not use local or global config file (plowshare.conf).
.TP
.B "   " --get-module
Get module(s) for URL(s) and quit. Useful for wrappers.
.TP
.BI "   " " " --printf "=FORMAT"
Don't process final link, print results in a given format (for each link). This can be useful for wrappers. Interpreted sequences are:
.RS
.TP
\fI%%\fR
raw % character
.TP
\fI%c\fR
final cookie file (with full path)
.TP
\fI%C\fR
%c or empty string if module does not require it
.TP
\fI%d\fR
download (final) url
.TP
\fI%f\fR
destination (local) filename
.TP
\fI%F\fR
destination (local) filename (with output directory)
.TP
\fI%m\fR
module name
.TP
\fI%n\fR
newline
.TP
\fI%t\fR
tabulation character
.TP
\fI%u\fR
download (source) url
.RE
.TP
.BI "   " " " --exec "=COMMAND"
Don't process final link, execute command (for each link). This can be useful to run external download manager (like wget).
Interpreted sequences are the same used by \fI--printf\fP option.

If this option is used several times, the last one will be used.
.SS Generic program information
.TP
.B -h, --help
Display main help and exit.
.TP
.B -H, --longhelp
Display complete help (with module options) and exit.
.TP
.B "   " --version
Output version information and exit.

.\" ****************************************************************************
.\" * Modules options                                                          *
.\" ****************************************************************************
.SH "MODULE OPTIONS"

.SS Common options
.TP
.BI -a, " " --auth "=USER:PASSWORD"
Use premium account.
.TP
.BI -b, " " --auth-free "=USER:PASSWORD"
Use free account.
.TP
.BI -p, " " --link-password "=PASSWORD"
Used for password-protected files.
.P
All switches are not implemented nor required for all modules.
See long help message for detailed modules option list.

.\" ****************************************************************************
.\" * Notes                                                                    *
.\" ****************************************************************************
.SH NOTES

.SS
Command line authentication string format
Complete login must have
.I USER:PASSWORD
format. The first semi-colon character is the separator. So,
.I PASSWORD
can contain a semi-colon character without any trouble.
.TP
Don't forget to single-quote string if your password contain shell expandable characters (like space, $ or &).

.\" ****************************************************************************
.\" * Examples                                                                 *
.\" ****************************************************************************
.SH EXAMPLES

.SS 1) Download one or several files
.nf
$ plowdown http://www.rapidshare.com/files/12345678/foo.rar
.sp 1
# Downloads are successive (not parallel)
$ plowdown http://depositfiles.com/files/fv2u9xqya http://hotfile.com/dl/68261330/2f2926f/
.sp 1
# Download a password-protected file from mediafire
$ plowdown \-p somepassword http://www.mediafire.com/?mt0egmhietj60iy
.sp 1
# Download using an account (free or premium, not supported by all modules)
$ plowdown \-a myuser:mypassword http://hotfile.com/dl/68261330/2f2926f/
.fi
.SS 2) Download a list of links (one link per line) commenting out (with #) those successfully downloaded 
.nf
$ plowdown \-m file_with_links.txt
.fi
.SS 3) Download with restrictions
.nf
$ plowdown \-\-max\-rate 900K \-i eth1 http://depositfiles.com/files/fv2u9xqya
.fi
.SS 4) Download with a proxy (3128 is the default port)
.nf
$ export http_proxy=http://192.168.0.20:80
.sp 0
$ plowdown http://www.rapidshare.com/files/12345678/foo.rar
.fi
.SS 5) Filter alive links in a text file 
.nf
$ plowdown \-c file_with_links.txt > file_with_active_links.txt
.fi
.SS 6) Use an alternatice web retriever for the final file download
.nf
$ plowdown \-\-exec 'wget \-\-load\-cookies %c \-O "%f" %d' http://uploading.com/files/39267me4/foo.zip/
.fi
.SS 7) Safe download. Each URL will be limited in the number of tries and wait delays.
.nf
$ alias plowdown='plowdown \-\-no\-overwrite \-\-max\-retries=10 \-\-timeout=3600'
.sp 0
$ plowdown \-m file_with_links.txt
.fi

.\" ****************************************************************************
.\" * Files                                                                    *
.\" ****************************************************************************
.SH "FILES"
.TP
.I ~/.config/plowshare/plowshare.conf
This is the per-user configuration file. 
.TP
.I /etc/plowshare.conf
Systemwide configuration file.
.PP
The file format is described in
.BR plowshare.conf (5).

.\" ****************************************************************************
.\" * Exit codes                                                               *
.\" ****************************************************************************
.SH "EXIT CODES"

Possible exit codes are: 
.IP 0 
Success. It also means that link is alive if plowdown is invoked with \fI-c/--check-link\fP command-line option.
.IP 1
Fatal error. Upstream site updated or unexpected result.
.IP 2
No available module (provided URL is not supported).
.IP 3
Network error. Mostly curl related.
.IP 4
Authentication failed (bad login/password).
.IP 5
Timeout reached (refer to \fI-t/--timeout\fP command-line option).
.IP 6
Maximumn tries reached (refer to \fI-r/--max-retries\fP command-line option).
.IP 7
Captcha generic error.
.IP 8
System generic error.
.IP 10
Link alive but temporarily unavailable.
.IP 11
Link alive but requires a password.
.IP 12
Link alive but requires some authentication (private or premium link).
.IP 13
Link is dead.
.IP 14
Can't download link because file is too big (need permissions).
.IP 15
Unknown command line parameter or incompatible options.
.PP
If
.B plowdown
is invoked with multiple links or link-list files and one or several errors occur, the first error code is returned added with 100.

.\" ****************************************************************************
.\" * Authors / See Also                                                       *
.\" ****************************************************************************
.SH AUTHORS
Plowshare was initially written by Arnau Sanchez. See the AUTHORS file for a list of some of the many other contributors.

Plowshare is (C) 2010-2012 The Plowshare Team
.SH "SEE ALSO"
.BR plowup (1),
.BR plowdel (1),
.BR plowlist (1),
.BR plowshare.conf (5).
